v0.26.0

[!IMPORTANT]
This version supersede v0.25.0 (now deprecated) because of a small breaking change: although it technically is a breaking change, it is about the new IFusionCacheMemoryLocker introduced just a week ago, so unless you are already implementing your own custom memory locker it will not be a problem.

Apart from this, v0.26.0 is basically the same as v0.25.0, so please update to v0.26.0 as soon as possible so you'll be ready for the big v1.0 that will be released very soon.

🔭 OpenTelemetry support (docs)

FusionCache now natively supports full observability, thanks to the great native support of OpenTelemetry in .NET via the core Activity and Meter classes without any extra dependency to produce them.

In general, the 3 main signals in the observability world are traces, metrics and logs.

FusionCache always supported logging, and even in a pretty advanced and customizable way.

Now the two remaining pieces are finally here: traces and metrics.

It is possible to opt-in to generate traces and metrics for both:

• high-level operations: things like GetOrSet/Set/Remove operations, Hit/Miss events, etc
• low-level operations: things like memory/distributed level operations, backplane events, etc

There's also a new package specific for OpenTelemetry that adds native support to instrument our applications, with FusionCache specific options ready to use, like including low-level signals or not.

It is then possible to simply plug one of the existing OpenTelemetry-compatible collectors for systems like Jaeger, Prometheus or Honeycomb and voilà, there we have full observability of our FusionCache instances.

Here's an example of how to set it up without dependency injection:

// SETUP TRACES
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .AddFusionCacheInstrumentation()
  .AddConsoleExporter()
  .Build();

// SETUP METRICS
using var meterProvider = Sdk.CreateMeterProviderBuilder()
  .AddFusionCacheInstrumentation()
  .AddConsoleExporter()
  .Build();

or, via dependency injection:

services.AddOpenTelemetry()
  // SETUP TRACES
  .WithTracing(tracing => tracing
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter()
  )
  // SETUP METRICS
  .WithMetrics(metrics => metrics
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter()
  );

The end result of all of this, when viewed for example in Honeycomb, is something like this:

Quite nice, uh 😏 ?

Oh, and I can't thank @​martinjt enough for the support!

See here for the issue.

🔒 Extensible Memory Locker

FusionCache always protected us from the Cache Stampede problem, but the internals of the memory locking mechanism have always been private.

Now no more, and thanks to the new IFusionCacheMemoryLocker interface the community may come up with different designs and implementations.

The builder has also been extended with support for configuring different memory lockers thanks to new methods like WithRegisteredMemoryLocker, WithMemoryLocker(locker), WithStandardMemoryLocker() and more.

See here for the issue.

NOTE: this version contains a small breaking change regarding the params in the methods of IFusionCacheMemoryLocker (swapped the position of key and operationId, to be 100% consistent with the rest of the codebase. As explained in the note at the top it is something that realistically will not change anything, but it's good to know.

🐞 Fixed a minor SkipDistributedCacheReadWhenStale bug

Thanks to community member @​angularsen I fixed a small bug related to SkipDistributedCacheReadWhenStale not working as expected during get-only operations (TryGet, GetOrDefault).

See here for the issue.

↩️ Better items cleanup for auto-recovery

Minor, but still: FusionCache now better cleans up processed auto-recovery items.

📕 Docs

Updated some docs and added some new ones (Observability, etc).

v0.25.0: (⚠️ deprecated)

[!IMPORTANT]
This version has been superseded by v0.26.0 because of a small breaking change: although it technically is a breaking change, it is about the new IFusionCacheMemoryLocker introduced just a week ago, so unless you are already implementing your own custom memory locker it will not be a problem.

Apart from this, v0.26.0 is basically the same as v0.25.0, so please update to v0.26.0 as soon as possible so you'll be ready for the big v1.0 that will be released very soon.

🔭 OpenTelemetry support (docs)

FusionCache now natively supports full observability, thanks to the great native support of OpenTelemetry in .NET via the core Activity and Meter classes without any extra dependency to produce them.

In general, the 3 main signals in the observability world are traces, metrics and logs.

FusionCache always supported logging, and even in a pretty advanced and customizable way.

Now the two remaining pieces are finally here: traces and metrics.

It is possible to opt-in to generate traces and metrics for both:

• high-level operations: things like GetOrSet/Set/Remove operations, Hit/Miss events, etc
• low-level operations: things like memory/distributed level operations, backplane events, etc

There's also a new package specific for OpenTelemetry that adds native support to instrument our applications, with FusionCache specific options ready to use, like including low-level signals or not.

It is then possible to simply plug one of the existing OpenTelemetry-compatible collectors for systems like Jaeger, Prometheus or Honeycomb and voilà, there we have full observability of our FusionCache instances.

Here's an example of how to set it up without dependency injection:

// SETUP TRACES
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .AddFusionCacheInstrumentation()
  .AddConsoleExporter()
  .Build();

// SETUP METRICS
using var meterProvider = Sdk.CreateMeterProviderBuilder()
  .AddFusionCacheInstrumentation()
  .AddConsoleExporter()
  .Build();

or, via dependency injection:

services.AddOpenTelemetry()
  // SETUP TRACES
  .WithTracing(tracing => tracing
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter()
  )
  // SETUP METRICS
  .WithMetrics(metrics => metrics
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter()
  );

The end result of all of this, when viewed for example in Honeycomb, is something like this:

Quite nice, uh 😏 ?

Oh, and I can't thank @​martinjt enough for the support!

See here for the issue.

🔒 Extensible Memory Locker

FusionCache always protected us from the Cache Stampede problem, but the internals of the memory locking mechanism have always been private.

Now no more, and thanks to the new IFusionCacheMemoryLocker interface the community may come up with different designs and implementations.

The builder has also been extended with support for configuring different memory lockers thanks to new methods like WithRegisteredMemoryLocker, WithMemoryLocker(locker), WithStandardMemoryLocker() and more.

See here for the issue.

🐞 Fixed a minor SkipDistributedCacheReadWhenStale bug

Thanks to community member @​angularsen I fixed a small bug related to SkipDistributedCacheReadWhenStale not working as expected during get-only operations (TryGet, GetOrDefault).

See here for the issue.

↩️ Better items cleanup for auto-recovery

Minor, but still: FusionCache now better cleans up processed auto-recovery items.

📕 Docs

Updated some docs and added some new ones (Observability, etc).

v0.24.0

⚠️ Update Notes

If you are updating from a previous version, please read here.

↩️ Brand new Auto-Recovery (docs)

The old Backplane Auto-Recovery is now, simply, Auto-Recovery!

It shines above the other features as a way to automatically handle and resolve transient errors with timed retries and other techniques, to do the best it can to avoid leaving your cache in a dire situation, no matter what.

Lately I proceeded with an almost complete rewrite of the internals of the entire distributed part, meaning both the distributed cache and the backplane, and in particular the auto-recovery feature to make it all even better..

This is the culmination of many months of research, experimentation, development, testing, benchmarking and in general a lot of work.

The new Auto-Recovery now supports both the distributed cache and the backplane, either individually or together.

Now it is also active, meaning it handles retries automatically instead of waiting for an external signal to "wake up".

Some of these improvements include:

• continuous background processing (more robust)
• queue automatic cleanup
• active detection and processing of re-connection
• the distributed cache and the backplane now work together even more (and better) than before, with granular control of re-sync operations needed
• better handling of connection/subscription errors
• better logging

Every edge case I thought of and all the others reported to me by the community are handled, all automatically.

You can read some of them at the dedicated docs page.

Please note that all the existing options named BackplaneAutoRecoveryXyz are now named simply AutoRecoveryXyz: this is not a breaking change though, since the old ones are still present but marked with the useful [Obsolete] attribute. Simply update to the latest version, recompile, look for some warnings and do the appropriate changes, if any.

🖥️ Simulator (docs)

In general it is quite complicated to understand what is going on in a distributed system.

When using FusionCache with the distributed cache and the backplane, a lot of stuff is going on at any given time: add to that intermittent transient errors and, even if we can be confident auto-recovery will handle it all automatically, clearly seeing the whole picture can become a daunting task.

It would be very useful to have something that let us clearly see it all in action, something that would let us configure different components, tweak some options, enable this, disable that and let us simulate a realistic workload to see the results.

Luckily there is, and is called Simulator.

📢 Better Backplane (docs)

This version introduces a better way to handle incoming backplane messages: long story short, it will now take less time for a change to be propagated to all the other nodes, and to be reflected into their local memory cache (only if necessary, to save resources).

📞 Eviction event now pass the cache value (docs)

Thanks to a request by community member @​giulianob the Eviction event in the memory cache has been made more powerful, and is now passing the cache value being evicted.

This can be useful for example to dispose a value being evicted from the cache, or more.

See here for more.

💥 Custom Exceptions

FusionCache now has 3 new custom exception types that are used to generalize errors of 3 main types: distributed cache errors, serialization errors and backplane errors.

In this way it will be easier to catch exception "groups" in our code instead of special-case it to work with Redis, CosmosDB, etc.

In case the old behaviour is needed for some reason, we can simply set the ReThrowOriginalExceptions options to true.

🕑 Better timestamping

Timestamps are now more precise, and are used more inside the various heuristics used to handle conflicts and more.

⚙️ Added ReThrowBackplaneExceptions option

It is now possible to more granularly specify if we want to re-throw exceptions happened in the backplane code.

To allow this though we need to disable background execution of the backplane (via the AllowBackgroundBackplaneOperations option), otherwise it would be physically impossible to re-throw them.

📜 Better Logging

Logging messages are now even better, with more useful information.

One that shines in particular and that is fundamental in debugging distributed issues is the inclusion of the InstanceId on top of the CacheName: with this we can better identify who sent messages to who without any doubt.

🔴 Add support for ConnectionMultiplexerFactory in RedisBackplane

It is now possible to directly pass an instance of IConnectionMultiplexer to waste less resources, thanks to a PR by the community user @​JeffreyM .

Thanks Jeffrey!

🐞 NullFusionCache now correctly handles CreateEntryOptions

Thanks to a bug report by community member @​kelko , a small issue has been fixed with the standard NullFusionCache implementation.

See here for more.

🐵 New base AbstractChaosComponent

Historically all the chaos-related components (eg: ChaosBackplane, ChaosDistributedCache, etc) all re-implement the same core properties and methods to control throws probability, random delays and so on.

Now that these components exist for some time and they are working well, they needed a little refactoring.

So a new AbstractChaosComponent has been created acting as a base class for all chaos-related components, so that they now all inherit from it to result in less code and better evolvability.

See here for more.

🐵 Added support for cancellation in chaos components

Chaos components now supports cancellation via the standard use of CancellationTokens.

✅ Better Tests

The tests have been reorganized, better splitted into different files, they now have a unique abstract base class with some common useful stuff and most of them now have logging enabled, just in case.

📕 Docs

Finally I've updated a lot of the existing docs and added some new ones, like for the brand new AutoRecovery feature, for the Simulator and more.